

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Introduction &mdash; quippy 7ea04c5+ documentation</title>
  

  
  
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
  
  
  

  
  <script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
        <script type="text/javascript" src="../_static/language_data.js"></script>
        <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
        <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "math|output_area", "processEscapes": true, "ignoreClass": "document", "inlineMath": [["$", "$"], ["\\(", "\\)"]]}})</script>
    
    <script type="text/javascript" src="../_static/js/theme.js"></script>

    

  
  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Theoretical background" href="adaptive-qmmm-theory.html" />
    <link rel="prev" title="Adaptive QM/MM MD of Fracture in Silicon" href="adaptive-qmmm.html" /> 
</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          

          
            <a href="../index.html" class="icon icon-home"> quippy
          

          
            
            <img src="../_static/hybrid.png" class="logo" alt="Logo"/>
          
          </a>

          
            
            
              <div class="version">
                7ea04c5+
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
    
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../intro.html">Introduction to <code class="docutils literal notranslate"><span class="pre">quippy</span></code></a></li>
<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation of QUIP and quippy</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tutorials</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="Introduction.html">Getting started with <code class="docutils literal notranslate"><span class="pre">Atoms</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="quippy-ase-interoperability.html">Interoperability with Atomic Simulation Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html">Introductory Tutorial</a></li>
<li class="toctree-l2"><a class="reference internal" href="quippy-descriptor-tutorial.html">Using Quippy to compute descriptors of atomic environments</a></li>
<li class="toctree-l2"><a class="reference internal" href="adglass.html">Molecular Dynamics Simulation of Fracture in Quartz</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="adaptive-qmmm.html">Adaptive QM/MM MD of Fracture in Silicon</a><ul class="current">
<li class="toctree-l3 current"><a class="current reference internal" href="#">Introduction</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#scope-of-the-tutorial">Scope of the tutorial</a></li>
<li class="toctree-l4"><a class="reference internal" href="#practical-considerations">Practical considerations</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="adaptive-qmmm-theory.html">Theoretical background</a></li>
<li class="toctree-l3"><a class="reference internal" href="adaptive-qmmm-step1.html">Step 1: Setup of the Silicon model system</a></li>
<li class="toctree-l3"><a class="reference internal" href="adaptive-qmmm-step2.html">Step 2: Classical MD simulation of fracture in Si</a></li>
<li class="toctree-l3"><a class="reference internal" href="adaptive-qmmm-step3.html">Step 3: LOTF hybrid MD simulation of fracture in Si</a></li>
<li class="toctree-l3"><a class="reference internal" href="adaptive-qmmm-solutions.html">Solutions</a></li>
<li class="toctree-l3"><a class="reference internal" href="adaptive-qmmm-references.html">References</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../quippy.html">Quippy library reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../visualisation.html">Visualisation Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fortran_wrapper.html">Appendix: wrapping Fortran 90 Code</a></li>
<li class="toctree-l1"><a class="reference internal" href="../teach_sparse.html">Command line options of the teach_sparse main program</a></li>
</ul>

            
          
    <p></p>
    <ul>
        <li><a href="../genindex.html">Index</a></li>
        <li><a href="../py-modindex.html">Module Index</a></li>
        <li><a href="../search.html">Search Page</a></li>
        <li><a href="../_modules/index.html">Module Source Code</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">quippy</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../index.html">Docs</a> &raquo;</li>
        
          <li><a href="index.html">Tutorials</a> &raquo;</li>
        
          <li><a href="adaptive-qmmm.html">Adaptive QM/MM MD of Fracture in Silicon</a> &raquo;</li>
        
      <li>Introduction</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="../_sources/Tutorials/adaptive-qmmm-step0.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  
<style>
/* CSS overrides for sphinx_rtd_theme */

/* 24px margin */
.nbinput.nblast,
.nboutput.nblast {
    margin-bottom: 19px;  /* padding has already 5px */
}

/* ... except between code cells! */
.nblast + .nbinput {
    margin-top: -19px;
}

.admonition > p:before {
    margin-right: 4px;  /* make room for the exclamation icon */
}

/* Fix math alignment, see https://github.com/rtfd/sphinx_rtd_theme/pull/686 */
.math {
    text-align: unset;
}
</style>
<div class="section" id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<div class="section" id="scope-of-the-tutorial">
<h2>Scope of the tutorial<a class="headerlink" href="#scope-of-the-tutorial" title="Permalink to this headline">¶</a></h2>
<p>In this tutorial, we will carry out classical and hybrid multiscale
QM/MM (quantum mechanics/molecular mechanics) molecular dynamics
simulations using the Learn on the Fly (LOTF) schmee for fracture in
silicon. For the classical simulations we will use the
Stillinger-Weber <a class="reference internal" href="adaptive-qmmm-references.html#stillinger1985" id="id1">[Stillinger1985]</a> interatomic potential, which
provides a generally good description of many properties of silicon,
but, not, however of brittle fracture as we will see. The focus of the
tutorial is on embedding techniques, so we will use an approximate
quantum mechanical method which demonstrates the approach while
remaining fast enough to carry out calculations during the time
available, namely Density Functional Tight Binding <a class="reference internal" href="adaptive-qmmm-references.html#elstner1998" id="id2">[Elstner1998]</a>.</p>
<p>The tutorial is divided into three sections. There are also some
extension tasks at the end which you can complete if you have time. In
the first section we will prepare the model fracture system for our
simulations. In the second part, we will carry out classical molecular
dynamics, and in the third part of the tutorial, the ‘Learn on the
Fly’ (<a class="reference internal" href="adaptive-qmmm-references.html#devita1998" id="id3">[DeVita1998]</a>, <a class="reference internal" href="adaptive-qmmm-references.html#csanyi2004" id="id4">[Csanyi2004]</a>) embedding scheme will be used to
carry out coupled classical and quantum calculations. One of the main
advantages of the LOTF approach is that the QM region can be moved
during the simulation (<em>adaptive</em> QM/MM). You can read more details
about multiscale embedding methods applied to materials systems in
<a class="reference internal" href="adaptive-qmmm-references.html#bernstein2009" id="id5">[Bernstein2009]</a>, and more about brittle fracture in silicon
investigated with the ‘Learn on the Fly’ technique in <a class="reference internal" href="adaptive-qmmm-references.html#kermode2008" id="id6">[Kermode2008]</a>.</p>
</div>
<div class="section" id="practical-considerations">
<span id="practical"></span><h2>Practical considerations<a class="headerlink" href="#practical-considerations" title="Permalink to this headline">¶</a></h2>
<p>In this tutorial we will carry out simulations using a combination of
two packages: <a class="reference external" href="http://www.jrkermode.co.uk/quippy">quippy</a>, a Python
interface to the <a class="reference external" href="http://www.libatoms.org">libAtoms/QUIP</a> MD code
developed at King’s College London, Cambridge University, the Naval
Research Lab in Washington and the Fraunhofer IWM in Freiburg, and the
Atomic Simulation Environment, <a class="reference external" href="https://wiki.fysik.dtu.dk/ase">ASE</a>,
a Python framework developed at the Centre for Atomistic Materials
Design (<a class="reference external" href="http://www.camd.dtu.dk/">CAMd</a>) at DTU, Copenhagen.</p>
<p>If you’re not familiar with Python don’t worry, it’s quite easy to
pick up and the syntax is very similar to Fortran. We have provided
template Python code which you should copy and paste into your text
editor. Save your script with a <code class="docutils literal notranslate"><span class="pre">.py</span></code> file extension. Whenever you
see <code class="docutils literal notranslate"><span class="pre">...</span></code> it means there is something you need to add to the code in
order to complete it; usually there will be a comment to give you a
hint. The source code listings are all in boxes like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span> <span class="s1">&#39;Example code listing&#39;</span>     <span class="c1"># Print something out</span>
<span class="nb">print</span> <span class="o">...</span>                        <span class="c1"># You need to add something here</span>
                                 <span class="c1"># e.g. replace the ... with a number</span>
</pre></div>
</div>
<p>To run code, we will be using <a class="reference external" href="http://ipython.org">ipython</a>, an
interactive Python shell. You can start <cite>ipython</cite> with a simple shell
command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ipython
</pre></div>
</div>
<p>Start by importing everything from the <cite>quippy</cite> package with the
command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">In</span> <span class="p">[</span><span class="mi">1</span><span class="p">]:</span> <span class="kn">from</span> <span class="nn">qlab</span> <span class="k">import</span> <span class="o">*</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>If you have not installed the <cite>AtomEye</cite> plugin then the command
above will give an <code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code>. You can use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">quippy</span> <span class="k">import</span> <span class="o">*</span>
</pre></div>
</div>
<p class="last">instead, which only imports <cite>quippy</cite> and not <cite>AtomEye</cite>, but you
will then not be able to visualise interactively using the
<a class="reference internal" href="../qlab.html#qlab.view" title="qlab.view"><code class="xref py py-func docutils literal notranslate"><span class="pre">view()</span></code></a> function - you can always save configurations to
external files and visualise them with other tools such as <a class="reference external" href="http://www.ks.uiuc.edu/Research/vmd/">VMD</a> or <a class="reference external" href="http://www.ovito.org">OVITO</a> instead. See the <a class="reference internal" href="../qlab.html#module-qlab" title="qlab: Interactive visualisation of atomic systems"><code class="xref py py-mod docutils literal notranslate"><span class="pre">qlab</span></code></a> and
<a class="reference internal" href="../atomeye.html#module-atomeye" title="atomeye: AtomEye atomistic configuration viewer"><code class="xref py py-mod docutils literal notranslate"><span class="pre">atomeye</span></code></a> documentation for further details.</p>
</div>
<p>You should prepare your Python scripts in a text editor and then run
them from within <cite>ipython</cite> with the <a class="reference external" href="http://ipython.org/ipython-doc/stable/interactive/tutorial.html#running-and-editing">%run</a>
command. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">In</span> <span class="p">[</span><span class="mi">2</span><span class="p">]:</span> <span class="n">run</span> <span class="n">make_crack</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>If your script is taking a long time to run and you realise something
is wrong you can interrupt it with <cite>Ctrl+C</cite>.</p>
<p>The tutorial is structured so that you will build up your script as
you go along. You should keep the same <cite>ipython</cite> session open, and
simply run the script again each time you add something new. You will
find it easier to follow the tutorial if you use the same variable
names as we have used here.</p>
<p>You can also execute individual Python statements by typing them
directly into the <cite>ipython</cite> shell. This is very useful for debugging
and for interactive visualisation (described in more detail in the
<a class="reference internal" href="adaptive-qmmm-step2.html#visualisation2"><span class="std std-ref">2.3 Visualisation and Analysis (as time permits)</span></a> section). Finally, it’s possible to copy and
paste code into <cite>ipython</cite> using the <cite>%paste</cite> or <cite>%cpaste</cite> commands.</p>
<p>You can follow the links in the tutorial to read more documentation for
functions and classes we will be using, and for <cite>quippy</cite> routines you
can also browse the source code by clicking on the <cite>[source]</cite> link
which you will find to the right of class and function definitions in
the online documentations. You can also explore functions
interactively from within <cite>ipython</cite> by following the name of an object
or function with a <code class="docutils literal notranslate"><span class="pre">?</span></code>, e.g.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>In [3]: Atoms ?
</pre></div>
</div>
<p>displays information about the <a class="reference internal" href="../atoms.html#quippy.atoms.Atoms" title="quippy.atoms.Atoms"><code class="xref py py-class docutils literal notranslate"><span class="pre">Atoms</span></code></a> class, or</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>In [4]: write ?
</pre></div>
</div>
<p>displays information about the <a class="reference internal" href="../io.html#quippy.io.write" title="quippy.io.write"><code class="xref py py-func docutils literal notranslate"><span class="pre">write()</span></code></a> function. See
the <a class="reference external" href="http://ipython.org/ipython-doc/stable/interactive/tutorial.html">ipython tutorial</a>
for more information.</p>
<p>Each subsection indicates the approximate amount of time you should
spend on it. At the end of each subsection there is a <em>Milestone</em>
where a script for that stage of the tutorial is provided. If you run
out of time, just skip ahead to the next milestone, download the
script and then continue with the next section.</p>
<p>Continue with <a class="reference internal" href="adaptive-qmmm-step1.html#step1"><span class="std std-ref">Step 1: Setup of the Silicon model system</span></a>.</p>
</div>
</div>


           </div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="adaptive-qmmm-theory.html" class="btn btn-neutral float-right" title="Theoretical background" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="adaptive-qmmm.html" class="btn btn-neutral float-left" title="Adaptive QM/MM MD of Fracture in Silicon" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2008-2016, James Kermode

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>